feat(vm): support corporate HTTP forward proxy egress for microVM sandboxes - #3090

Summary

Gives the MicroVM compute driver the same operator-owned corporate forward-proxy surface the Podman and Kubernetes drivers already have, so VM sandboxes on proxy-only corporate networks can reach the destinations policy allows. The supervisor-side machinery from #1792 is reused unchanged; what this adds is the per-driver half — configuration, validation, a driver→guest argument channel, and credential/CA delivery into the guest.

Related Issue

Closes #3088

Note for reviewers on issue state: #3088 currently carries only state:triage-needed — it has no state:accepted, no roadmap placement, and no agent:plan-requested/agent:implementation-requested label. This work was done on an explicit maintainer request rather than through the unattended queue. Per AGENTS.md that request authorizes the phase, and no lifecycle labels were changed. Flagging it because PRs for features are otherwise expected to link an accepted issue.

Changes

The argv channel (the one genuinely new mechanism). Podman and Kubernetes build the supervisor's command line in Rust. The VM guest init script runs as PID 1 and execs a fixed argv, and libkrun's krun_set_exec receives an empty argument array, so there was no channel for driver-owned supervisor arguments. The supervisor's proxy flags deliberately have no env = fallback, and build_guest_environment merges user-supplied environment, so the guest environment is not a safe transport either.

• The driver writes /opt/openshell/supervisor-args into the overlay upperdir on every launch; the guest init script reads it verbatim, one argument per line (no word splitting, globbing, or expansion), and appends it to every supervisor exec.
• It is written even when empty. That is what makes the channel unforgeable: the upperdir always shadows the read-only image layer, so a sandbox image can neither supply its own supervisor arguments by baking a file at that path nor disable the operator's by omitting one. This mirrors the existing init.d manifest, which solves the same trust problem for guest init drop-ins.
• Because both launch backends exec the same init script, this lands once and covers libkrun and QEMU. runtime.rs is untouched.

Configuration. [openshell.drivers.vm] accepts https_proxy, no_proxy, proxy_auth_file, proxy_auth_allow_insecure, proxy_connect_by_hostname, and proxy_ca_bundle, with matching --https-proxy…--proxy-ca-bundle flags and OPENSHELL_VM_* environment variables on the driver binary (needed independently, since the driver also runs as an external gRPC driver). The booleans travel as explicit values rather than presence flags so an operator's explicit false survives the gateway→driver hop and still trips the pairing checks. The keys are not inheritable from [openshell.gateway] and are rejected by template.driver_config.vm.

Shared validation, fail-closed. Added openshell_core::driver_utils::validate_upstream_proxy_settings holding the pairing rules the Podman driver established, called by both the gateway and the driver — without the gateway-side check an invalid table surfaces as an opaque driver-readiness timeout instead of an error naming the key. Podman and Kubernetes are deliberately left on their own copies to keep this PR scoped.

Credential and CA delivery. A microVM has no bind mounts or container secrets, so both are staged into the per-sandbox overlay the way the gateway JWT already is — credential root-only at 0600, CA at 0644, both at fixed /opt/openshell paths, both rewritten every launch (so removing a setting clears material a previous launch staged into a preserved overlay), and both removed with the sandbox state directory.

Docs. docs/reference/gateway-config.mdx (MicroVM section), docs/reference/sandbox-compute-drivers.mdx, crates/openshell-driver-vm/README.md, architecture/sandbox.md, and a VM corporate-proxy troubleshooting section in the debug-openshell-cluster skill.

Security considerations for review

• Credential at rest in the overlay image. feat(vm): support corporate HTTP forward proxy egress for microVM sandboxes #3088 explicitly deferred this to review. The credential ends up inside the per-sandbox overlay.ext4 on the gateway host, which differs from the Podman secret model. It is taken because the per-sandbox gateway JWT — a bearer token for the gateway — already travels this exact path, so the exposure is not new; it is documented in architecture/sandbox.md and the config reference rather than left implicit. Alternatives considered and rejected as disproportionate: copying to tmpfs via an init drop-in and deleting from the overlay, or a new driver→guest vsock secret channel.
• Reachability. Guest egress leaves through gvproxy, so a proxy on the gateway host's loopback is reachable only via host.openshell.internal (gvproxy NATs 192.168.127.254 to the host's 127.0.0.1). Documented, and exercised by the e2e. The guest→gateway callback is unaffected and never traverses the proxy.
• Runtime capabilities unchanged. The VM driver still advertises no policy DNS or transparent TCP interception; this PR does not change what traffic reaches the supervisor's proxy.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Unit — 29 new tests:

• openshell-core: the shared validator (unsupported scheme, inline credentials, present-but-empty values, each auxiliary key without a proxy URL, the cleartext acknowledgement including the https:// exemption, CA bundle valid with a plain-HTTP intercepting proxy) and the three new guest paths in the control-root test.
• openshell-driver-vm: argv builder emits guest paths and never the operator's host paths; Some(false) is not passed as a presence flag; the argument file renders empty when unconfigured and one-argument-per-line otherwise, preserving values containing spaces; newline/NUL values rejected; credential and CA validated with the supervisor's own validators and errors never echo file contents; build_guest_environment emits no proxy setting and no user-supplied environment can forge an --upstream-* argument; template.driver_config.vm rejects all six keys; Debug redacts the proxy URL and credential path.
• openshell-server: spawn forwards the settings as driver argv and omits unset ones; invalid config is rejected before the driver starts, naming the key.

E2E — new e2e/rust/tests/vm_corporate_proxy.rs in the e2e:vm lane, the VM counterpart of podman_corporate_proxy.rs. Fixtures run as host processes (no container-runtime dependency for this lane) and are reached from the guest through host.openshell.internal, which is also what proves the documented host-loopback reachability rule. Three cases:

1. A policy-approved HTTPS destination reached through the proxy — the proxy log records CONNECT 192.168.127.254:<port> auth=ok, proving both the validated-IP CONNECT target and that the overlay-staged credential reached the supervisor (the proxy answers 407 without it). The policy-denied destination never appears in the proxy log at all, and a port-qualified no_proxy destination is reached while never touching the proxy.
2. An https:// proxy trusted via proxy_ca_bundle, with the CA minted by the fixture and recovered from its output.
3. Fail-closed: no_proxy without https_proxy stops the gateway from serving, with the offending keys named in its log.

Verification performed on this branch:

smoke passing is a deliberate regression signal: every sandbox now runs the argument reader before the supervisor exec, so a mistake in the reader or in the empty-array expansion under set -u would break ordinary VM boot, not just the proxy path.

Two notes for anyone running the VM lane locally on macOS, both discovered here and neither a product bug:

• brew install e2fsprogs is required — the driver shells out to mke2fs on the host to build the guest rootfs. It is keg-only; the driver probes /opt/homebrew/opt/e2fsprogs/sbin directly.
• VM sandbox main-process commands must stay short. libkrun passes the guest environment on the kernel command line and the driver base64-encodes the main-process spec into it, so a ~1000+ character command aborts the VM before boot with a libkrun TooLarge panic. E2E workloads of any size should use SandboxGuard::create (delivered via ExecSandbox) rather than create_keep_with_args.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)